---
layout: docs
page_title: Migration Guide - Active Directory - Secrets Engines
description: >-
  The guide for migrating from the Active Directory secrets engine to the LDAP secrets engine.
---

# Migration guide - active directory secrets engine

The Vault [Active Directory secrets engine](/vault/docs/secrets/ad) has been deprecated as
of the Vault 1.13 release. This document provides guidance for migrating from the Active
Directory secrets engine to the [LDAP secrets engine](/vault/docs/secrets/ldap) that was
introduced in Vault 1.12.

## Deprecation timeline

Beginning from the Vault 1.13 release, we will continue to support the Active Directory (AD)
secrets engine in maintenance mode for six major Vault releases. Maintenance mode means that
we will fix bugs and security issues, but no new features will be added. All new feature
development efforts will go towards the unified LDAP secrets engine. At Vault 1.18, we will
mark the AD secrets engine as [pending removal](/vault/docs/deprecation/faq#pending-removal).
At this time, Vault will begin to strongly signal operators that they need to migrate off of
the AD secrets engine. At Vault 1.19, we will mark the AD secrets engine as
[removed](/vault/docs/deprecation/faq#removed). At this time, the AD secrets engine will be
removed from Vault. Vault will not start up with the AD secrets engine mounts enabled.

## Migration steps

The following sections detail how to migrate the AD secrets engine configuration and
applications consuming secrets to the new LDAP secrets engine.

### 1. enable LDAP secrets engine

The LDAP secrets engine needs to be enabled in order to have a target for migration of
existing AD secrets engine mounts. AD secrets engine mounts should be mapped 1-to-1 with
new LDAP secrets engine mounts.

To enable the LDAP secrets engine:

```shell-session
$ vault secrets enable ldap
```

To enable at a custom path:

```shell-session
$ vault secrets enable -path=<custom_path> ldap
```

If enabled at a custom path, the `/ldap/` path segment in API paths must be replaced with
the custom path value.

### 2. migrate configuration

The AD secrets engine [configuration](/vault/api-docs/secret/ad#configuration)
will need to be migrated to an LDAP secrets engine [configuration](/vault/api-docs/secret/ldap#configuration-management).
The API paths and parameters will need to be considered during the migration.

#### API path

| AD Secrets Engine | LDAP Secrets Engine |
| ----------------- |-------------------- |
| [/ad/config](/vault/api-docs/secret/ad#configuration) | [/ldap/config](/vault/api-docs/secret/ad#configuration)    |

#### Parameters

The parameters from existing AD secrets engine configurations can generally be mapped 1-to-1
to LDAP secrets engine configuration. The following LDAP secrets engine parameters are the
exception and must be considered during the migration.

| AD Secrets Engine | LDAP Secrets Engine | Details |
| ----------------- | ------------------- | ------- |
| N/A | [schema](/vault/api-docs/secret/ldap#schema) | Must be set to the `ad` option on the LDAP secrets engine configuration. |
| [userdn](/vault/api-docs/secret/ad#userdn) | [userdn](/vault/api-docs/secret/ad#userdn) | Required to be set if using the [library sets](#4-migrate-library-sets) check-out feature. It can be optionally set if using the [static roles](#3-migrate-roles) feature without providing a distinguished name ([dn](/vault/api-docs/secret/ldap#dn)). |
| [ttl](/vault/api-docs/secret/ad#ttl) | N/A | Replaced by static role [rotation_period](/vault/api-docs/secret/ldap#rotation_period). |
| [max_ttl](/vault/api-docs/secret/ad#max_ttl) | N/A | Not supported for [static roles](#3-migrate-roles). Can be set using [max_ttl](/vault/api-docs/secret/ldap#max_ttl-1) for library sets. |
| [last_rotation_tolerance](/vault/api-docs/secret/ad#last_rotation_tolerance) | N/A | Not supported by the LDAP secrets engine. Passwords will be rotated based on the static role [rotation_period](/vault/api-docs/secret/ldap#rotation_period). |

### 3. migrate roles

AD secrets engine [roles](/vault/api-docs/secret/ad#role-management) will need to be migrated
to LDAP secrets engine [static roles](/vault/api-docs/secret/ldap#static-roles). The API paths,
parameters, and rotation periods will need to be considered during the migration.

#### API path

| AD Secrets Engine | LDAP Secrets Engine |
| ----------------- | ------------------- |
| [/ad/roles/:role_name](/vault/api-docs/secret/ad#role-management) | [/ldap/static-role/:role_name](/vault/api-docs/secret/ldap#static-roles) |

#### Parameters

The following parameters must be migrated.

| AD Secrets Engine | LDAP Secrets Engine | Details |
| ----------------- | ------------------- | ------- |
| [ttl](/vault/api-docs/secret/ad#ttl-1) | [rotation_period](/vault/api-docs/secret/ldap#rotation_period) | N/A |
| [service_account_name](/vault/api-docs/secret/ad#service_account_name) | [username](/vault/api-docs/secret/ldap#username)    | If `username` is set without setting the [dn](/vault/api-docs/secret/ldap#dn) value, then the configuration [userdn](/vault/api-docs/secret/ldap#userdn) must also be set. |

#### Rotation periods

Rotations that occur from AD secrets engine [roles](/vault/api-docs/secret/ad#role-management)
may conflict with rotations performed by LDAP secrets engine [static roles](/vault/api-docs/secret/ldap#static-roles)
during the migration process. This could cause applications consuming passwords to read a
password that gets invalidated by a rotation shortly after. To mitigate this, it's recommended
to set an initial [rotation_period](/vault/api-docs/secret/ldap#rotation_period) that provides
a large enough window to complete [application migrations](#5-migrate-applications) to minimize
the chance of this happening. Additionally, tuning the AD secrets engine [last_rotation_tolerance](/vault/api-docs/secret/ad#last_rotation_tolerance)
parameter could help mitigate applications reading stale passwords, since the parameter allows
rotation of the password if it's been rotated out-of-band within a given duration.


<Note title="Lazy rotation vs automatic rotation">

  The AD secrets engine uses **lazy rotation** for passwords. With lazy
  rotation, passwords rotate whenever the engine receives a request for a role
  whose rotation period has elapsed.
  
  The LDAP secret engine uses **automatic rotation** for passwords. With
  automatic rotation, passwords are rotated as soon as the rotation period
  elapses, without waiting for a client request.

  When migrating to the LDAP secret engine, you may need to account for the
  rotation changes in your clients.  For example, if your client assumes the
  password does not change until its next request to Vault and uses the password
  to verify against other services.

</Note>

### 4. migrate library sets

AD secrets engine [library sets](/vault/api-docs/secret/ad#library-management) will need to
be migrated to LDAP secrets engine [library sets](/vault/api-docs/secret/ldap#library-set-management).
The API paths and parameters will need to be considered during the migration.

#### API path

| AD Secrets Engine | LDAP Secrets Engine |
| ----------------- | ------------------- |
| [/ad/library/:set_name](/vault/api-docs/secret/ad#library-management) | [/ldap/library/:set_name](/vault/api-docs/secret/ldap#library-set-management) |

#### Parameters

The parameters from existing AD secrets engine library sets can be exactly mapped 1-to-1
to LDAP secrets engine library sets. There are no exceptions to consider.

### 5. migrate applications

The AD secrets engine provides APIs to obtain credentials for AD users and service accounts.
Applications, or Vault clients, are typically the consumer of these credentials. For applications
to successfully migrate, they must begin using new API paths and response formats provided
by the LDAP secrets engine. Additionally, they must obtain a Vault [token](/vault/docs/concepts/tokens)
with an ACL [policy](/vault/docs/concepts/policies) that authorizes access to the new APIs.
The following section details credential-providing APIs and how their response formats differ
between the AD secrets engine and LDAP secrets engine.

#### API paths

| AD Secrets Engine | LDAP Secrets Engine | Details |
| ----------------- | ------------------- | ------- |
| [/ad/creds/:role_name](/vault/api-docs/secret/ad#retrieving-passwords) | [/ldap/static-cred/:role_name](/vault/api-docs/secret/ldap#static-role-passwords) | Response formats differ. Namely, `current_password` is now `password`.  See [AD response](/vault/api-docs/secret/ad#sample-get-response) and [LDAP response](/vault/api-docs/secret/ldap#sample-get-response-1) for the difference. |
| [/ad/library/:set_name/check-out](/vault/api-docs/secret/ad#check-a-credential-out) | [/ldap/library/:set_name/check-out](/vault/api-docs/secret/ldap#check-out-management) | Response formats do not differ. |
| [/ad/library/:set_name/check-in](/vault/api-docs/secret/ad#check-a-credential-in) | [/ldap/library/:set_name/check-in](/vault/api-docs/secret/ldap#check-in-management) | Response formats do not differ. |

### 6. disable AD secrets engines

AD secrets engine mounts can be disabled after successful migration of configuration and
applications to the LDAP secrets engine. Note that disabling the secrets engine will erase
its configuration from storage. This cannot be reversed.

To disable the AD secrets engine:

```shell-session
$ vault secrets disable ad
```

To disable at a custom path:

```shell-session
$ vault secrets disable <custom_path>
```
